Skip to content

[documentation / submitty.org] Containerize documentation site#748

Open
Pavan-Srivathsa wants to merge 2 commits intoSubmitty:mainfrom
Pavan-Srivathsa:containerize-docs-site
Open

[documentation / submitty.org] Containerize documentation site#748
Pavan-Srivathsa wants to merge 2 commits intoSubmitty:mainfrom
Pavan-Srivathsa:containerize-docs-site

Conversation

@Pavan-Srivathsa
Copy link
Copy Markdown

Why is this Change Important & Necessary?

Building the documentation site requires installing Ruby and managing
gem dependencies locally, which is painful for infrequent contributors
(as noted in Submitty/Submitty#12685). Ruby version conflicts and native
extension compilation failures are common pain points.

What is the New Behavior?

Contributors can now run the documentation site with a single command:
docker compose up

No Ruby, Bundler, or gem installation required. The setup includes:

  • Volume mounts for live reload (edits show instantly)
  • A named volume for gem caching (fast restarts)
  • Force polling for cross-platform file change detection
  • LiveReload for automatic browser refresh

What steps should a reviewer take to test?

  1. Install Docker if not already installed
  2. Clone this branch
  3. Run docker compose up --build
  4. Verify the site loads at http://localhost:4000
  5. Edit any markdown file in _docs/ and confirm the browser refreshes
  6. Run docker compose down && docker compose up to confirm fast restart
  7. Optionally test the link checker:
    docker compose exec docs bundle exec jekyll build
    docker compose exec docs bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external

Automated Testing & Documentation

README.md updated with Docker setup instructions. Existing Ruby/Bundler
instructions preserved. No automated test changes needed.

Other information

Not a breaking change. No migrations required.
Resolves Submitty/Submitty#12685

@Pavan-Srivathsa Pavan-Srivathsa force-pushed the containerize-docs-site branch from 940ade1 to b436c07 Compare April 11, 2026 19:27
@williamjallen
Copy link
Copy Markdown
Member

Hi @Pavan-Srivathsa, thanks for this contribution. Unfortunately it looks like there's an error with the host configuration. I see the following in the console when I follow the directions listed in this PR: Not allowed to use restricted network host "0.0.0.0": http://0.0.0.0:4000/index/overview

Copy link
Copy Markdown
Member

@williamjallen williamjallen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes as per above comment.

@github-project-automation github-project-automation Bot moved this from Seeking Reviewer to Work in Progress in Submitty Development Apr 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Work in Progress

Development

Successfully merging this pull request may close these issues.

Containerize documentation site

2 participants